# Custom Chains

In this tutorial, we will go through the steps of connecting to a custom Chain, that's not listed as part of [known Chains](https://github.com/TrueFiEng/useDApp/tree/master/packages/core/src/model/chain).

## Prerequisites

The tutorial assumes the user has already started with the basics of `useDApp`.

See the [Getting Started](/docs) guide if you are a new user.

## Motivation

The typical use of `useDApp` is to connect to a well known chain, such as Ethereum Mainnet or xDai chain.

However if your use case is to connect to a lesser known chain, or a custom one created by your team, this tutorial uncovers the steps required to connect `useDApp` to any chain.

As a first step, see if your chain is not already listed in the list of [known Chains](https://github.com/TrueFiEng/useDApp/tree/master/packages/core/src/model/chain).

## Create the custom chain object

The first step is to create a Chain configuration object with all the required information regarding the custom chain.

### Example

```tsx title="tutorial-chain.ts"
import { Chain } from '@usedapp/core'

export const TutorialChain: Chain = {
  chainId: 99999,
  chainName: 'TutorialChain',
  isTestChain: false,
  isLocalChain: false,
  multicallAddress: '0x0000000000000000000000000000000000000000',
  getExplorerAddressLink: (address: string) => `https://tutorialchain.etherscan.io/address/${address}`,
  getExplorerTransactionLink: (transactionHash: string) => `https://tutorialchain.etherscan.io/tx/${transactionHash}`,
  // Optional parameters:
  rpcUrl: 'https://rpc.tutorialchain.io',
  blockExplorerUrl: 'https://tutorialchain.etherscan.io',
  nativeCurrency: {
    name: 'TutorialCoin',
    symbol: 'TUT',
    decimals: 18,
  }
}
// IMPORTANT: Fill that object with your own data.
```

### Explanation

Field | Meaning
--- | ---
`chainId` | The ID of the chain. Every chain has a unique `chainId`
`chainName` | The name of the chain
`isTestChain` | Whether the chain is a testnet, such as Kovan or Ropsten
`isLocalChain` | Whether the chain is a development chain running on localhost
`multicallAddress` | An address of the [Multicall](https://github.com/makerdao/multicall) contract on the chain
`getExplorerAddressLink` | A function to construct a link to a blockchain explorer, based on an ethereum address
`getExplorerTransactionLink` | A function to construct a link to a blockchain explorer, based on a transaction hash
`rpcUrl` | (Optional) an RPC url. At least one is required if you want your app to be able to add new networks to Metamask
`blockExplorerUrl` | (Optional) a block explorer address, optional for adding the network to Metamask
`nativeCurrency` | (Optional) native currency, optional for adding the network to Metamask (otherwise it will refault to ETH). Please refer to [Metamask docs](https://docs.metamask.io/guide/rpc-api.html#wallet-addethereumchain) or the example above

### multicallAddress

[Multicall](https://github.com/makerdao/multicall) aggregates results from multiple contract constant function calls.

It is required for `useDApp` to operate.

If there is no known Multicall contract deployed on your custom chain, it needs to be deployed and address configured as `multicallAddress`. For deployment, [Mars](https://github.com/TrueFiEng/Mars) deployment tool can be used.

If the chain is a local development chain, the Multicall contract is automatically deployed for you by `useDApp`.

## Include your custom chain in Config

With the custom chain config created and saved in `tutorial-chain.ts` file, you can include it in `useDApp` Config object that was introduced in the [Getting Started example](/docs#example).

The new Config object with your custom chain will be passed into the `<DAppProvider>` component.

````diff
  import {
    Mainnet,
    DAppProvider,
    useEtherBalance,
    useEthers,
    Config,
+   DEFAULT_SUPPORTED_CHAINS,
  } from '@usedapp/core'
  import { formatEther } from '@ethersproject/units'

  import App from 'App'
+ import { TutorialChain } from './tutorial-chain'

  const config: Config = {
-     readOnlyChainId: Mainnet.chainId,
+     readOnlyChainId: TutorialChain.chainId,
    readOnlyUrls: {
      [Mainnet.chainId]: 'https://mainnet.infura.io/v3/62687d1a985d4508b2b7a24827551934',
+     [TutorialChain.chainId]: '<url of the custom chain>',
    },
+   networks: [...DEFAULT_SUPPORTED_CHAINS, TutorialChain],
  }

  ReactDOM.render(
    <React.StrictMode>
      <DAppProvider config={config}>
        <App />
      </DAppProvider>
    </React.StrictMode>,
    document.getElementById('root')
  )
````

You're fully setup - now in the `<App>` component, you can use the functionality provided by `useDApp` to access your TutorialChain.

## Send a PR to `useDApp` (optional)

If you want to add your custom chain to the list of known chains, you can send a PR to the [useDApp repository](https://github.com/TrueFiEng/useDApp).
In your PR, please make sure to include the following changes:

- Add file describing your chain to the `packages/core/src/model/chain` directory. Please name the file `<chainName>.ts`. For example, if your chain is called `TutorialChain`, the file name should be `tutorial-chain.ts`. The file should export one object that implements the `Chain` interface. The example chain object is provided in the first step of this tutorial.
- Next please make sure to import and reexport the added file from `packages/core/src/model/chain/index.ts` file.
- Add your chain to the `DEFAULT_SUPPORTED_CHAINS` array in `packages/core/src/constants/chainId.ts` file.

When submitting a PR, please make sure to include the short description and motivation of the changes.

This step is optional - Send a PR with your custom chain if you think other users will benefit from it.

### Example PR

- [ThunderCore](https://github.com/TrueFiEng/useDApp/pull/553) chain

## Summary

In this tutorial, we went through the steps required for using `useDApp` with a custom chain that is not included by default.

We created the custom chain object which includes all the required information about the chain.

Next, we included the custom chain in `useDApp` config and optionally created a PR for `useDApp` to include the custom chain in the set of default chains.
